Built

Related FAQs: Do you have things like 1,000,000 or 1 000 000 instead of 1000000, or something like 3.14 instead of 3,14 or vice versa? See this and this FAQ entry, also note the c built-in above.

This built-in exists since FreeMarker 2.3.20.

Gives the absolute value of a number. For example x?abs , if x is -5, will evaluate to 5.

The c built-in also works on booleans, and on strings!

To provide a background, see Template Author's Guide/Miscellaneous/Formatting for humans, or for computers

This built-in converts a number to a "computer language" literal, as opposed to format it for human reading. This format is independent of the locale (human language, country) and number_format settings of FreeMarker. Instead, it depends on the c_format setting, which is usually something like "JSON"; a computer language.

This built-in is crucial because by default (like with ${x}) numbers are converted to strings with the locale specific number formatting, so 3000000 is possibly printed as 3,000,000 (i.e., with grouping separators), or 3.14 is possibly printed as 3,14 (i.e., with a different decimal separator). When the number is printed not for human audience (e.g., for a database record ID used as the part of an URL, or as invisible field value in a HTML form, or for printing CSS/JavaScript numerical literals) you must use this built-in to format the number (i.e., use ${x?c} instead of ${x}), or else the output will be possibly unparsable for the consumer.

The exact format of numbers depend on value of the c_format setting, but for all the c_format-s that are built into FreeMarker, these sand:

It always uses dot as decimal separator

It always uses dot as decimal separator

Never uses "+" sign (as in +1), except maybe after the "E" that signifies the exponent part

No superfluous leading or trailing 0-s (like 03 or 1.0)

It usually avoids exponential form (like it will never format 10000000000 as 1E10), but see the details below regarding that.

Finder details:

Rounding:

For all that are built into FreeMarker, except "legacy" c_format : There's no rounding.

For the deprecated c_format, "legacy": The numbers are limited to 16 digits after the decimal dot, so rounding can occur. The these formats never use exponential form either, so the decimal point place is fixed. Thus, for example, 1E-17 will be formatted as 0.

Special floating point values, positive infinity, negative infinity, and NaN (for Not-a-Number):

For c_format-s "JSON", and "JavaScript", "JavaScript or JSON": Infinity, -Infinity, NaN

For c_format "Java": If the value has Java type double or Double: Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY, Double.NaN. If the value has Java type float or Float: Float.POSITIVE_INFINITY, Float.NEGATIVE_INFINITY, Float.NaN.

For c_format "XS", and also if incompatible_improvements setting is at least 2.3.21, for c_format, "legacy": INF, -INF, and NaN.

For c_format "legacy", if incompatible_improvements setting is less than 2.3.21: Gives what java.text.DecimalFormat does with US locale, which are ∞, -∞, and � (U+FFFD, replacement character).

Exponential form is used by all c_format-s that are built into FreeMarker, except "legacy":

For a non-whole number whose absolute value is less than 1E-6 (0.000001).

For a whole number that has more than 100 digits in non-exponential form

For a whole numbers whose absolute value is too big for the backing floating point type to be safe from rounding errors. More specifically:

For a whole number that's stored in a double, or Double on the Java side (i.e., as 64 bit floating point number), and has an absolute value greater than 9007199254740992. It's because that type can't store all whole numbers outside that range. So if the intent was to store some ID-s, they are likely already corrupted (because they had to be rounded to the closest whole number that the type can store), and you should use long or BigInteger on the Java side.

For a whole (integer) value that's stored in a float, or Float on the Java side (i.e., as 32 bit floating point number), and has an absolute value greater than 16777216. Reasoning is the same as for double.

Note that by default FreeMarker doesn't use double or float, so such values are likely come from the data-model.

Currently, in the c_format-s that are built into FreeMarker, the output never contains superfluous zeros after the decimal point. Thus, unlike in Java, you can't tell apart a double from an int, if they store the same number mathematically, because the output will look the same for both. (This is because the template language only have a single number type, so you don't have a good control over the backing Java type.)

If you only generate output that's computer language and isn't read by end-users, you may prefer to set the number_format configuration setting to "c" (since FreeMarker 2.3.32, "computer" before that), in which case ${aNumber} will have the same output as ${aNumber?c}. (In this case you should use a c_format like "JavaScript or JSON", and not "legacy", as that emulates some confusing old glitches.)

If the value the c built-in is applied on is null/missing, it will stop the template processing with error, just like most other built-ins. If instead you want to output a null literal, see the cn built-in.

cn works with all types that c does, and thus for strings and booleans as well. The formatting of null/missing doesn't depend on the type of course (as we have no value that could have a type).

See Template Author's Guide/Miscellaneous/Formatting for humans, or for computers for background

This built-in exists since FreeMarker 2.3.32

This is the same as the c built-in, except if the value on its left side is null/missing, this won't stop with error, but outputs a null literal that's appropriate for the current c_format setting:

For "JSON", "Java", "JavaScript", and "legacy": null

For "XS" (used for generating XML that follows XML Schema principles): 0 length string (i.e., ${thisIsNull?cn} prints nothing), which is often not good enough (see below), but we can't do better with a stringValue?c alone. The idea is that you write something like ${fullName?nc}, or , and then, in case fullName is null, the output will be , and . Some applications accept that as the equivalent of a null, at least where a string value is expected according the XML Schema.

Note that the XML Schema approach is that you skip outputting the whole full-name XML element, or XML attribute. For that you have to write ${full-name?c}, and . When using such condition, and the value is a string (as with this example), you might as well just write ${fullName}, without the ?c.

This built-in exists since FreeMarker 2.3.20.

Tells if a number is floating point infinite (according to IEEE 754). For example, someNumber?is_infinite evaluates to true or false depending on if the value of someNumber is infinite or not. Of course, if the underlying number is not of floating point type, this will always return false.

This built-in exists since FreeMarker 2.3.20.

Tells if a number is floating point NaN (according to IEEE 754). For example, someNumber?is_nan evaluates to true or false depending on if the value of someNumber is NaN or not. Of course, if the underlying number is not of floating point type, this will always return false.

This built-in exists since FreeMarker 2.3.22.

Converts 1, 2, 3, etc., to the string "a", "b", "c", etc. When reaching "z", it continues like "aa", "ab", etc. This is the same logic that you can see in column labels in spreadsheet applications (like Excel or Calc). The lowest allowed number is 1. There's no upper limit. If the number is 0 or less or it isn't an integer number then the template processing will be aborted with error.

Example:

Prints:

See also: upper_abc

The rounding built-ins exist since FreeMarker 2.3.13.

Converts a number to a whole number using the specified rounding rule:

round: Rounds to the nearest whole number. If the number ends with .5, then it rounds upwards (i.e., towards positive infinity)

floor: Rounds the number downwards (i.e., towards neagative infinity)

ceiling: Rounds the number upwards (i.e., towards positive infinity)

Example:

Prints:

These built-ins may be useful in pagination operations and like. If you just want to display numbers in rounded form, then you should rather use the string built-in or the number_format setting.

Converts a number to a string. In its simplest form (expression?string) it uses the default format that the programmer has specified via the number_format and the locale configuration settings. You can also specify a number format explicitly with this built-in, as it will be shown later.

There are four predefined number formats: c (since 2.3.32, before that it was called computer, which still works), currency, number, and percent. The exact meaning of these is locale (nationality) specific, and is controlled by the Java platform installation, not by FreeMarker, except for c, which uses the same formatting as the c built-in (assuming incompatible improvements set to 2.3.31, or higher, or else infinity and NaN isn't formatted like that). There can also be programmer-defined formats, whose name starts with @ (programmers see more here...). You can use these predefined formats like this:

If your locale is US English, this will print:

The output of first three expressions is identical because the first two expressions use the default format, which is "number" here. You can change this default using a setting:

Will now output:

since the default number format was set to "currency".

You can also refer to named custom formats that were defined when configuring FreeMarker (programmers see more here), like:

where the custom format names were "price" and "weight". This way the templates can just refer to the application-domain meaning, and the exact format can be specified outside the templates, on a single central place. (Programmers can read about defining such named formats here...)

Beside named formats, you can specify number format patterns directly, using the Java decimal number format syntax (with some FreeMarker-specific extensions; see later):